---
title: Construct and initialize an application manager
summary: Bind an identity to a new manager instance and prepare its data layer.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-26
library: SAIF.Application
reference_type: embedded
operation_id: construct-and-initialize-an-application-manager
trigger: A derived manager (e.g. ClaimAppManager) is constructed by a front-end page or service caller
---

# Construct and initialize an application manager

Binds a `clsSecurityPrincipal` to a new manager instance at construction time, then runs the derived
class's initialization and data-layer provisioning steps in a fixed order.

| Field | Value |
| --- | --- |
| **Operation ID** | construct-and-initialize-an-application-manager |
| **Trigger** | A derived manager (e.g. `ClaimAppManager`) is constructed by a front-end page or service caller |
| **Inputs** | `inSecurityPrincipal As clsSecurityPrincipal` |
| **Outputs** | An initialized manager instance with a data layer ready for portal creation |
| **Primary components** | `AppManagerBase.New`, `AppManagerBase.Initialize` |
| **Entry point** | `SAIF.Application/AppManagerBase.vb` |

## Steps

1. **A front-end page or service caller instantiates a domain manager** (e.g. `ClaimAppManager`),
   passing in the `clsSecurityPrincipal` that represents the currently authenticated user. This is the
   only way to obtain a manager instance — the base class exposes no parameterless constructor, so it
   is impossible to construct a manager without first establishing whose identity it will act as
   ([BR-APP-001](../business-rules.md#br-app-001-manager-construction-requires-a-security-principal)).
   The constructor does nothing more than remember this principal in `m_SecurityPrincipal` for later
   use by authorization and data-portal logic; it performs no I/O and cannot fail on its own.
2. **The new instance starts out fully locked down.** Before any initialization logic runs, field
   initializers pin the manager's default state to the most restrictive values possible: security role
   is `NoAccess`, the business context is considered not-yet-set, any accumulated message text is
   empty, and the line separator used when rendering messages defaults to `<BR>` (an HTML break, since
   this is a web application). The practical effect is that if a derived class's initialization logic
   is ever skipped or throws partway through, the manager is left denying access rather than silently
   allowing it
   ([BR-APP-002](../business-rules.md#br-app-002-access-is-denied-by-default)).
3. **The caller then explicitly calls `Initialize()`** to bring the manager the rest of the way up.
   This is a separate step from construction by design — it lets the derived class finish setting
   itself up (via `OnInitialize()`, e.g. loading role-specific security classification) before it
   provisions its database connection (via `OnCreateDataLayer()`). The two always run in that fixed
   order: security/role setup first, data access second, so that a manager never ends up with a live
   database connection before its authorization state has been established.
4. **The database connection itself is deferred even further** — it is not created during
   `Initialize()`, but lazily on the first time any code actually reads the `DataLayer` property. When
   that first read happens, an `ApplicationDataAccess` instance is built using the authenticated
   user's own name (`SecurityPrincipal.UserName.ToString`) as the database client/batch identifier.
   This means every SQL statement the manager subsequently issues is attributable, at the database
   level, to the real end user who is logged into the application — not to a generic service account —
   unless a derived class later overrides that identity for a specific batch operation
   ([BR-APP-007](../business-rules.md#br-app-007-database-client-identity-is-the-requesting-user-unless-overridden)).

## Process flow

The following diagram visualizes this operation's control flow — object construction (identity
binding, lockdown-by-default), followed by the two-phase initialization sequence, followed by lazy
data-layer provisioning on first use.

```mermaid
flowchart TD
	Start(["Front-end page or service<br>caller instantiates a<br>domain manager"]) --> Bind["Constructor binds the<br>authenticated user's<br>clsSecurityPrincipal"]
	Bind --> Lockdown["Field initializers lock the<br>instance to NoAccess /<br>empty state by default"]
	Lockdown --> InitCall["Caller explicitly calls<br>Initialize"]
	InitCall --> OnInit["OnInitialize runs first:<br>derived class establishes<br>security role / context"]
	OnInit --> CreateLayer["OnCreateDataLayer runs<br>second: derived class<br>prepares portal settings"]
	CreateLayer --> Ready(["Manager instance ready;<br>no DB connection yet"])
	Ready --> FirstRead["First read of DataLayer<br>property"]
	FirstRead --> LazyCreate["ApplicationDataAccess is<br>created lazily, stamped<br>with the user's identity<br>as DB client id"]
	LazyCreate --> End(["Manager fully operational"])
```

## Failure and edge-case behavior
- No branch or error handling exists in this path; a `Nothing` principal would surface as a
  null-reference at the data-layer step.**

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)